Deploying Kanzi applications to Android

When you are developing Kanzi applications for Android you can use Android Studio, the Clang toolchain, and the Gradle build system. This development approach is tested on Ubuntu/Linux 16.04.5, Ubuntu/Linux 18.04.1, and Windows 10.

To build and deploy Kanzi applications created with Kanzi 3.6.3 or older, see Building and deploying Kanzi 3.6.3 and older applications to Android.

Requirements

To build and deploy Kanzi applications to Android devices using the Kanzi Android platform package, you need:

Installing the Android platform package

Extract the Kanzi Android platform package zip file to the <KanziWorkspace> directory. When you extract the zip file, skip duplicate files instead of overwriting those files.

Setting up the build environment

After you install the Kanzi Android platform package, set up your build environment.

To set up the build environment:

  1. Open Android Studio, in the Welcome screen select Configure, and in the dropdown menu select SDK Manager.
  2. In the SDK Manager window in the SDK Tools tab select CMake and NDK, and click OK.
    Android Studio installs the Android NDK and CMake you need for building and deploying Kanzi applications for Android.

Building and deploying Kanzi applications from Android Studio

If you want to use the Android platform package with Kanzi 3.6.4 or 3.6.5 applications, you can migrate the applications. See Migrating Kanzi 3.6.4 and 3.6.5 applications to use the Android platform package.

To build and deploy Kanzi applications from Android Studio:

  1. Open Android Studio and in the Welcome screen select Open an existing Android Studio project.
    The Open File or Project window opens.
  2. In the Open File or Project window go to <KanziWorkspace>/Projects/<ProjectName>/Application/configs/platforms and select the android_gradle project.
  3. In Android Studio in the main menu select Build > Make Project to build the application package.
    By default Android Studio uses the debug build configuration. When you build the Kanzi project, you can find the Android package at <KanziWorkspace>/Projects/<ProjectName>/Application/configs/platforms/android_gradle/app/build/outputs/apk/debug.
    To build using the release build configuration, open the Build Variants window and set the Build Variant to release.
    TIP

    If you do not specify the target architecture, Gradle builds the package for all supported platforms. You can set the architectures for which you want to build your package in build.gradle.

    android {
    defaultConfig {
        ndk {
            abiFilters 'arm64-v8a', 'x86'
        }
    }
}

  4. Deploy your Kanzi application to an Android device or an Android Virtual Device:
    1. Connect your Android device to your computer. To deploy to an Android Virtual Device, you must create one. See https://developer.android.com/studio/run/emulator.
    2. In the Android Studio main menu select Run > Run 'app' and select the device to which you want to deploy your application.

Building and deploying Kanzi applications from the command line

If you want to use the Android platform package with Kanzi 3.6.4 or 3.6.5 applications, you can migrate the applications. See Migrating Kanzi 3.6.4 and 3.6.5 applications to use the Android platform package.

You can build and deploy your Kanzi application to an Android device using the command line. In the <KanziWorkspace>/Engine/applications/kzb_player/configs/platforms/android_gradle directory:

Troubleshooting

Building and deploying Kanzi applications from Kanzi Studio

In Kanzi Studio you can build and deploy your Kanzi application to an Android device using a single command. This approach is useful when you want to see how your application works and looks on an Android device while you are still prototyping or developing your application.

Before you can build and deploy Kanzi applications from Kanzi Studio to Android devices, you need to set up the Kanzi build environment for Android and install on your computer the USB device drivers for your Android device. See Installing the Kanzi build environment for Android.

If your Kanzi application includes a Kanzi Engine plugin, you have to build and deploy your application manually. See Building and deploying Kanzi 3.6.3 and older applications to Android.

To build and deploy Kanzi applications from Kanzi Studio:

  1. If you add content to your application using the Kanzi Engine API, make sure to include that content in the <ProjectName>/configs/android/build.xml file in the <target name="-pre-compile"> target. For example, to add all .xml and .png files in the <ProjectName>/Application/bin directory use
    <target name="-pre-compile">
        <echo>Copying assets</echo>
        <copy todir="${asset.absolute.dir}">
            <fileset dir="${asset.absolute.dir}/../../../../bin">
                <include name="**/*.kzb"/>
                <include name="**/*.cfg"/>
                <include name="**/*.xml"/>
                <include name="**/*.png"/>
  2. Connect your Android device to your computer.
  3. In Kanzi Studio create or open the project for your Kanzi application and select File > Export > Build Android Package.
    Kanzi Studio builds the application source code, creates .apk package, and installs the package to your Android device.

Configuring Android builds

You can configure the building of your Kanzi applications for Android using the application configurations in Kanzi Studio. For example, you can set the target architecture, and whether Kanzi should deploy the built package to the attached target device. You can set which application configuration you want to use when you select File > Export > Build Android Package in Project > Properties in the Default Build Configuration property.

  1. In Kanzi Studio in the Library right-click Applications and select Create Application Configuration.
  2. In the Properties set the configuration for the Android build.
    For example:

Migrating Kanzi 3.6.4 and 3.6.5 applications to use the Android platform package

The Android platform package does not support the V8 library. Before you migrate your Kanzi application, disable or remove JavaScript from the Kanzi application that you want to migrate.

To migrate Kanzi 3.6.4 and 3.6.5 applications to use the Android platform package:

  1. Extract the Kanzi Android platform package zip file to the <KanziWorkspace> directory. When you extract the zip file, skip duplicate files instead of overwriting those files.
  2. Copy the <KanziWorkspace>/Engine/applications/kzb_player/configs/platforms/android_gradle directory to the <ProjectName>/Application/configs/platforms directory of the Kanzi application that you want to migrate to the new Android platform package.
  3. In your Kanzi application, edit the Java resources:
    1. In the android_gradle/app/src/main/java/com/rightware/kanzi/kzbplayer directory rename the KZBPlayer.java file to the name of your application.
      For example, if your project is called MyProject, rename the KZBPlayer.java file to MyProject.java.
    2. In the android_gradle/app/src/main/java/com/rightware/kanzi directory rename the kzbplayer directory to the lowercase name of your application.
      For example, if your application is called MyProject, rename the kzbplayer directory to myproject.
    3. In a text editor open the <project_name>.java file and edit the file to include the references to your application.
      For example, if your application is called MyProject:
      • Change
        com.rightware.kanzi.kzbplayer
        to
        com.rightware.kanzi.myproject
      • Change the class
        KZBPlayer
        to
        MyProject
      • Change the TAG
        "KZBPlayer"
        to
        "MyProject"
      • Change
        Debug.startMethodTracing("kzbplayer")
        to
        Debug.startMethodTracing("myproject")
    4. In a text editor open the android_gradle/app/src/main/AndroidManifest.xml file and edit the file to include the references to your application.
      For example, if your application is called MyProject:
      • Change
        com.rightware.kanzi.kzbplayer
        to
        com.rightware.kanzi.myproject
      • Change
        activity android:name=".KZBPlayer"
        to
        activity android:name=".MyProject"
    5. In a text editor open the android_gradle/app/src/main/res/values/strings.xml file and edit the file to include the name of your application.
      For example, if your application is called MyProject, change
      <string name="app_name">KZB Player</string>
      to
      <string name="app_name">MyProject</string>
  4. In your project, edit the build scripts:
    1. In a text editor open the android_gradle/app/CMakeLists.txt file and edit the file to include the name of your application and the path to the C++ application source file.
      For example, if your application is called MyProject:
      • Change
        project(kzb_player)
        to
        project(myproject)
      • Change
        add_executable(${PROJECT_NAME} src/main/cpp/kzb_player.cpp)
        to
        add_executable(${PROJECT_NAME} ../../../../src/myproject.cpp)
    2. In a text editor open the android_gradle/settings.gradle file and edit the file to include the name of your application.
      For example, if your application is called MyProject, set the value of the rootProject.name to "myproject".
    3. In a text editor open the android_gradle/app/build.gradle file and edit the file so that applicationId points to you application.
      For example, if your application is called MyProject, set the applicationId to "com.rightware.kanzi.myproject".
    4. In a text editor open the android_gradle/gradle.properties file and replace:
      org.gradle.jvmargs=-Xmx<size>m
      with
      org.gradle.jvmargs=-Xmx4608m
  5. In your application, edit the C++ source files:
    1. In the Application/src/<project_name>.cpp file change:
      class <ProjectName>: public ExampleApplication

      to

      class <ProjectName>: public Application
    2. In the <project_name>.cpp file add a registerMetadataOverride callback that does not contain V8Module registration:
      class <ProjectName>: public Application
{
public:
    ...
	
    virtual void registerMetadataOverride(ObjectFactory& /*factory*/) KZ_OVERRIDE
    {
        Domain* domain = getDomain();
        KanziComponentsModule::registerModule(domain);
    }
};
    3. In the <project_name>.cpp file in the onConfigure callback function remove references to the ExampleApplication class:
          virtual void onConfigure(ApplicationProperties& configuration) KZ_OVERRIDE
    {
        Application::onConfigure(configuration);
        configuration.binaryName = "<project_name>.kzb.cfg";
        configuration.extensionOutputEnabled = true;
        configuration.defaultSurfaceProperties.antiAliasing = 0;
        configuration.defaultSurfaceProperties.bitsDepthBuffer = 0;
        configuration.defaultSurfaceProperties.bitsStencil = 0;
    }
  6. Build and deploy your Kanzi application using either Android Studio or the command line interface. See Deploying Kanzi applications to Android and Deploying Kanzi applications to Android.

Building and deploying Kanzi 3.6.3 and older applications to Android

NOTE

Use this approach to build and deploy to Android only Kanzi applications made with Kanzi 3.6.3 or older.

SCons runs the SConstruct file in the configuration directory of the platform from which you run the scons command. SConstruct file is the entry point for building the application and contains the information about the Kanzi Engine location and runs these files:

To build and deploy Kanzi 3.6.3 and older applications to Android:

  1. If you add content to your application using the Kanzi Engine API, make sure to include that content in the <ProjectName>/configs/android/build.xml file in the <target name="-pre-compile"> target. For example, to add all .xml and .png files in the <ProjectName>/Application/bin directory use
    <target name="-pre-compile">
        <echo>Copying assets</echo>
        <copy todir="${asset.absolute.dir}">
            <fileset dir="${asset.absolute.dir}/../../../../bin">
                <include name="**/*.kzb"/>
                <include name="**/*.cfg"/>
                <include name="**/*.xml"/>
                <include name="**/*.png"/>
  2. Connect your Android device to your computer.
  3. Open the command line in the configuration directory of the platform for which you want to build the Kanzi application (<ProjectName>/Application/configs/platforms/<PlatformName>) and make sure you have the correct environmental variables set. See Setting the Kanzi environment variables.
    For example, to build your Kanzi application for:
  4. Run the scons command with the build parameters for your Kanzi application.

    Syntaxscons <library> <type> <name>
    Parameters
    library

    (Optional) the graphics library:

    • ES2 builds the application with OpenGL ES 2.0
    • GL builds the application with OpenGL
    type

    (Optional) the build type:

    • Release builds the application with compiler optimizations enabled. The release option builds smaller files than the debug option. Use this option for production purposes. Default value.
    • Debug builds the application with disabled compiler optimizations and contains full debug information you can use with a debugger. The debug option builds larger files and debug applications run slower. Use this option for development purposes.
    • Profiling builds the application with compiler optimizations enabled and links the application against the Profiling build. Use this option when you want to measure the performance of different parts of Kanzi Engine. For example, when you want to find out how much time Kanzi uses on different tasks during application startup, or which parts of the application take a lot of time to run. See Measuring application performance.
    name(Optional) the name of the project
    Examples

    // Builds the application with the default settings as specified
// in config.py and SConstruct configuration files.
scons
    // Builds the debug version of the application with
// the OpenGL graphics library.
scons GL debug
    // Builds the debug version of the application with the
// OpenGL ES 2.0 graphics library from the Kanzi Studio
// project named MyProject.
scons ES2 debug MyProject

    Scons builds the Kanzi application source code and binary files in the <ProjectName>/Application/output directory.

  5. In the <ProjectName>/Application/output directory run adb install or ant release install to install the .apk package of your Kanzi application on your Android device.
    For example, if your project is called MyProject and is stored in the <KanziWorkspace> run:
    adb install MyProject.apk

    or
    ant release install

Setting the Java version for Kanzi applications

To set the Java version for your Kanzi applications for Android, add to the Application/configs/platforms/android/build.xml as the first child elements of the top level <project> element and set the value attribute to the Java version you want to use

<property name="java.target" value="7" />
<property name="java.source" value="7" />

Troubleshooting

See also

Developing Kanzi applications for Android

Kanzi Android API reference

Installing the Kanzi build environment for Android

Building Kanzi applications for Android using a script

Installing the Kanzi build environment manually

Tutorial: Create a simple in-vehicle infotainment application

Android OEM USB Drivers

Deploying Kanzi applications

Open topic with navigation